communitymgtfandomcom-20200213-history
Technical barriers
= Introduction = Technical barriers to entry are technical obstacles that make contributing to a project harder than necessary. There are many ways in which these barriers can be lowered, and those will be covered here also. Although the focus is on software projects, much of this can be applied to other types of projects. In general, many of these barriers have to do with the skills users have. Few are expert system administrators, software developers and familiar with OSS all at the same time, so making things as simple as possible for the users (=potential contributors) usually pays back. I've found it useful to visualize the whole process the user goes through from the time he/she first downloads the software all the way up to becoming a contributor. This makes it easier to spot any technical barriers to entry there might be. = Installation barriers = Before a user can become a contributor he/she needs to be able to install and use the software in question. Therefore, making sure users can easily install your software is important. There are a few ways to lower this barrier: * Make sure the build process is as smooth as possible: you can't possibly provide packages for every imageanable platform and architecture. * Provide packages for various common operating systems and distributions, such as Windows, Debian, Ubuntu, Fedora and MacOSX. * Provide custom software repositories (e.g. apt or yum) with latest software for your users. This is especially useful in getting people to use the latest code and thus quickly provide bug reports. * Work with downstream distributors: try to get your software into OS-specific software repositories (e.g. Debian, Ubuntu) and application stores (e.g. Android Market). * Make the configuring the software as simple as possible (mentioned here). . If flexibility and the inherent complexity is necessary, you can still simplify things by defining sane defaults. Once user is running your software, he/she can start contributing. Many of the ways to contribute don't even require being able to build the application. = Build barriers = Users that need to extend the software first need to be able to build it. If they can't they can't test their changes or send in patches. A good worst-case example is Zimbra. Fortunately it's fairly easy to streamline the build process: * Document the build process properly in one place. Link to external resources where appropriate. In any case, the user should not need to hunt for instructions. * Use open source compilers, build tools, version control systems and programming languages. * Use a well-known series build steps whenever possible (e.g. mvn install or ./configure && make && make install). * Minimize the number of unnecessary external dependencies. * Use build dependencies with relatively stable APIs (as mentioned here). * Document all build- and runtime dependencies properly. * If the application is isolated from the rest of the system, consider providing build dependency packages which save community developers a lot of time. * Make sure the build system can be easily replicated even on different OS platforms: this helps spot and fix environment-specific parts. A smooth build process ensures that the maximum amount of users are able to use and build your software, and later hopefully contribute something back. = Development barriers = There are a few things that make it more difficult for users to change the code in a useful fashion: * Use of uncommon programming languages (as mentioned here * Use of multiple programming languages at the same time * Modularity of the codebase (e.g. simple extension points) * Complexity of codebase = Contribution barriers = Once the user has changed the code, there are potentially still some technical barriers in the way. For example: * Requiring users to base their patches on latest development code. While this is generally a good idea, it forces some contributors to learn a version control system they're not familiar with. It's probably a good idea to be flexible with one-time contributors. * Requiring bug/patch tracker registration or mailing list subscription before submitting patches. Again, in general this is a good idea, so that contributors can be traced back, e.g. if the patch needs modifications. However, there should be a more light-weight option, e.g. an IRC channel where users can post links to their patches. * Lack of communication and contribution tools (e.g. trackers, mailing lists and wikis) * Lack of documentation on how to contribute A good example of contribution barriers is the late SSL-Explorer project. = Case studies = Zimbra A good worst-case example for almost all build barriers is the Zimbra build process shortly after the FRANKLIN release. The build process had a number of problems, which the author of this article had to cope with: * Buildsystem bugs ** Build system was highly specialized and only usable for building Zimbra. That said, given Zimbra's architecture, there were really no alternatives. ** Total of 9 buildsystem bugs were encountered, many of which prevented building entirely. Clearly no attempt had been made to make the build system universally usable. In fact, it looked as if the company only had a single build computer sitting somewhere, and it had not been touched for a long while. * Multi-stage build process ** Build process was extremely complicated in general ** Several different build tools were used, e.g. autotools (for some dependencies) and Apache Ant (for Zimbra itself). * Lack of documentation ** The instructions for getting the source code were for the most part obsolete ** Build process was very poorly documented and scattered around the Internet and to various README/INSTALL files ** The documentation that was available was written by the community developers, not by Zimbra employees ** There were tons of undocumented or poorly documented build- and runtime dependencies * Proprietary version control system (Perforce) ** Use of a Perforce version control system and a single guest account meant that only one person could download the sources at the same time. Occasionally this meant that downloading the sources was interrupted in the middle, when somebody else connected with the same user account. ** The Perforce repository was occasionally down for days ** It was only possible to get the latest development code (HEAD) from the Perforce repository. Checking out code belonging to a certain release (e.g. FRANKLIN) or branch was impossible. In a nutshell, It was practically impossible to take the code, build it and send back patches. Fortunately, SSL-Explorer Another example of a poorly run project was SSL-Explorer, later forked as Adito by the author of this case-study. During the early phases of SSL-Explorer (until 1.0-rc17) was distributed in two forms: * Community Edition: entirely GPL licensed but encumbered with proprietary/unclearly licensed icons * Enterprise Edition: as above, but with several proprietary extensions (e.g. LDAP authentication, Drive mapping, nEXT support) As of sslexplorer-1.0.0-rc18 the community edition was discontinued and all subsequent versions of SSL-Explorer were closed source. 3sp closed the community forums in May 2008, and the company itself was eventually bought by Barracuda Networks. Original SSL-Eplorer had a number of issues as an open source project. During the time SSL-Explorer Community Edition was available, it was developed entirely by 3sp behind closed doors. Regular source- and binary releases were made, but users of SSL-Explorer had very limited means of participating in it's development: the only real communication channel between 3sp and SSL-Explorer's users were 3sp's user forums. This reduced the quality of interaction between SSL-Explorer's users and (3sp) developers in a few ways: * Lack of bug reporting facilities meant that there was no way to check if a bug was fixed or being fixed. Reporting and tracking bugs was also very hard, which made it harder for both the community and 3sp. * Lack of public source code repository meant that community developers could not verify whether an issue was fixed in development versions by 3sp. Also, any code that they might write might require significant changes after a new release. * Lack of a Wiki or similar meant there was no way to contribute documentation back to the project * The codebase was well-written and very modular, but at the same time very complex with very deep class inheritance hierarchies These technical barriers alone were enough to prevent most from contributing, but there was also the conflict of interest inherent to open core business models. There were of course psychological and social barriers as well. Probably due to all these difficulties the contributors faced, 3sp never even had the need for a Contributor License Agreement. This can only mean that they never got any significant contributions back from the community. After the project was later forked and all these barriers were taken down, a large number of community contributions were integrated into the software. Unfortunately, even so the project was a poor fit with a pure community-driven development model, so development eventually stagnated and stopped. A critical mass that could have kept the project going was never reached, possibly in part because of competition from existing SSL-Explorer Enterprise Edition installations which continued to work just fine.